CSS @property: Mastering Custom Property Type Definition and Validation

In the ever-evolving landscape of web development, staying ahead of the curve requires embracing new technologies and techniques that enhance efficiency, maintainability, and the overall user experience. CSS custom properties, also known as CSS variables, have revolutionized the way we manage and control styles. With the introduction of the @property at-rule, CSS gains an even more powerful tool: the ability to define and validate these custom properties, leading to more robust and predictable styling.

What is CSS @property?

The @property at-rule allows developers to define the type, syntax, and other characteristics of custom properties. Think of it as a way to provide structure and validation for your CSS variables. Before @property, CSS variables were essentially just strings of text that could hold anything. This lack of structure could lead to errors, making debugging more challenging and hindering the overall design consistency. @property addresses these issues by providing a mechanism to control the types of values that can be assigned to your custom properties.

Why Use CSS @property? Benefits and Advantages

The advantages of using @property are numerous and directly contribute to improved web development practices:

• Enhanced Code Maintainability: By explicitly defining the types and behaviors of custom properties, you make your code more self-documenting and easier to understand. Other developers (or your future self) will quickly grasp how a custom property is intended to be used.
• Improved Design Consistency: Validation ensures that only valid values are assigned to custom properties. This helps maintain a consistent visual appearance across your website or application.
• Robustness and Error Prevention: Invalid values will be rejected, preventing unexpected styling issues and reducing the time spent debugging.
• Dynamic Styling: @property enables better integration with JavaScript, allowing you to programmatically control and update your CSS variables with confidence, knowing the values are valid.
• Better Autocompletion and Developer Experience: Code editors can provide more intelligent autocompletion and code hints, helping developers write CSS more quickly and accurately.
• Optimized Performance: While the performance impact is generally small, validation can sometimes lead to minor optimizations by the browser.

Core Components of the @property Rule

The @property at-rule consists of several key components that define how a custom property behaves.

--property-name

This is the name of the custom property you are defining. It must begin with two hyphens (--), as is standard for CSS custom properties.

            @property --my-color { ... }
            

              
                Copy
              
            
          

syntax

The syntax descriptor defines the allowed type or pattern for the values of the custom property. It uses a subset of the CSS syntax and can take various values, including:

• <color>: Represents a color value (e.g., red, #FF0000, rgba(255, 0, 0, 1)).
• <length>: Represents a length value (e.g., 10px, 5em, 20%).
• <number>: Represents a numerical value (e.g., 10, 3.14).
• <percentage>: Represents a percentage value (e.g., 50%).
• <url>: Represents a URL (e.g., url('image.jpg')).
• <integer>: Represents an integer value (e.g., 10, -5).
• <angle>: Represents an angle value (e.g., 45deg, 0.5turn).
• <time>: Represents a time value (e.g., 2s, 200ms).
• <string>: Represents a string value.
• <image>: Represents an image value (same as url).
• *: Accepts any valid CSS value. This is a very permissive approach and should be used with caution.
• Combined types: You can combine multiple types using space-separated lists (e.g., <length> <length> <length> for defining three length values) or use the '|' symbol to allow any one of the listed types(e.g. <length> | <percentage> to support either a length or percentage).
• Custom Syntaxes: Custom syntaxes, for more complex scenarios, are often supported by custom implementations, though these will typically be described using regex-style syntax such as [a-z]+.

            
@property --base-color {
  syntax: <color>;
  inherits: false;
  initial-value: #333;
}

            

              
                Copy
              
            
          

inherits

The inherits descriptor determines whether the custom property inherits its value from its parent element. By default, custom properties do not inherit. This behavior can be controlled with a boolean value: true or false.

            
@property --font-size {
  syntax: <length>;
  inherits: true;
  initial-value: 16px;
}

            

              
                Copy
              
            
          

initial-value

The initial-value descriptor sets the default value of the custom property if it is not explicitly defined in the CSS. This provides a fallback value when the property is not specified, similar to the behavior of standard CSS properties.

            
@property --border-width {
  syntax: <length>;
  inherits: false;
  initial-value: 1px;
}

            

              
                Copy
              
            
          

Practical Examples

Let's dive into some practical examples to illustrate how to use @property effectively.

Example 1: Defining a Color Property

In this example, we define a custom property --primary-color to represent a primary color in our design system. We specify that it accepts only color values.

            
@property --primary-color {
  syntax: <color>;
  inherits: false;
  initial-value: #007bff;
}

body {
  --primary-color: #007bff; /* Valid */
  color: var(--primary-color);
}

h1 {
  --primary-color: rgb(255, 0, 0); /* Valid */
  color: var(--primary-color);
}

            

              
                Copy
              
            
          

Example 2: Defining a Length Property

Here, we define a custom property --spacing for managing spacing between elements, accepting length values. This example clearly demonstrates the value of setting an `initial-value` as a default for the entire site. This is especially useful when using a design system in which spacing defaults are defined.

            
@property --spacing {
  syntax: <length>;
  inherits: false;
  initial-value: 1rem;
}

p {
  margin-bottom: var(--spacing);
}

            

              
                Copy
              
            
          

Example 3: Defining an Integer Property

This example defines a custom property for the number of columns in a grid layout, validating that the value is an integer.

            
@property --grid-columns {
  syntax: <integer>;
  inherits: false;
  initial-value: 3;
}

.grid-container {
  display: grid;
  grid-template-columns: repeat(var(--grid-columns), 1fr);
}

            

              
                Copy
              
            
          

Example 4: Property Inheritance

Here we define a custom property that *will* be inherited. The `font-size` property set to `1rem` on the body will affect all its children unless overridden.

            
@property --font-size {
  syntax: <length>;
  inherits: true;
  initial-value: 1rem;
}

body {
  --font-size: 1rem;
  font-size: var(--font-size);
}

h2 {
  font-size: 1.25rem; /* Overrides inherited value */
}

            

              
                Copy
              
            
          

Example 5: Combining Types

Using the '|' operator, we can combine types. Here we accept either a `length` or a `percentage` for the shadow offset.

            
@property --shadow-offset {
  syntax: <length> | <percentage>;
  inherits: false;
  initial-value: 0;
}

.box {
  box-shadow: 0 var(--shadow-offset) var(--shadow-offset) gray;
}

            

              
                Copy
              
            
          

Best Practices for Using @property

To maximize the benefits of @property, follow these best practices:

• Define Properties in a Central Location: Group your @property definitions in a dedicated CSS file or section, often at the top of your main stylesheet or within a design system file. This promotes organization and makes it easy to manage your custom properties.
• Use Descriptive Property Names: Choose names that clearly indicate the purpose of each custom property (e.g., --primary-button-color, --header-font-size). This improves readability and understanding.
• Provide Comprehensive Documentation: Document your custom properties, including their syntax, usage, and any constraints. This documentation can be included in the form of comments alongside your CSS or in a separate style guide.
• Choose the Right Syntax: Carefully select the appropriate syntax for each property. Using the correct syntax prevents errors and ensures that the assigned values are valid.
• Consider Inheritance Carefully: Decide whether a property should inherit its value from its parent element. This depends on the property's nature and how it should be applied across your design.
• Use initial-value Strategically: Set an initial-value for all custom properties that require a default value. This provides a fallback and ensures that the style is applied even if the property isn't explicitly set.
• Leverage Design Systems: Integrate @property within your design system to maintain consistency and improve your team's development workflow. By using it in conjunction with other components, you build more robust and modular designs, which is often the goal when creating components for global usage.
• Test Thoroughly: Test your custom properties and their behavior across different browsers and devices to ensure compatibility and a consistent user experience. Cross-browser testing is a critical step, as the support of `property` is not yet universally implemented.

Browser Compatibility

As of October 26, 2023, the support for the @property at-rule varies across browsers. Chrome, Edge, and Safari have good support, while Firefox support is in a limited state. Always consult resources like Can I Use ([https://caniuse.com/mdn-css_at-rules_property](https://caniuse.com/mdn-css_at-rules_property)) to stay up-to-date on browser compatibility.

Important Considerations for Browser Compatibility:

• Feature Detection: Use feature detection techniques to gracefully handle browsers that don't support @property. You can use a CSS property check or JavaScript feature detection to apply alternative styles or polyfills.
• Progressive Enhancement: Design your website with a baseline styling that works without @property. Then, progressively enhance the design by adding @property support to compatible browsers.
• Polyfills and Fallbacks: Consider using polyfills or providing fallbacks for browsers that do not fully support @property. This might involve using plain CSS variables, or pre-processing using SASS, LESS or other methodologies.

Using CSS @property with JavaScript

One of the greatest advantages of CSS custom properties is their ability to be manipulated with JavaScript, enabling dynamic styling and enhanced user experiences. @property enhances this capability, making the integration between CSS and JavaScript even more powerful and predictable.

Here's how you can interact with custom properties defined using @property in JavaScript:

1. Getting a Custom Property Value: Use getPropertyValue() to retrieve the value of a custom property.

               
   const element = document.querySelector('.my-element');
   const primaryColor = getComputedStyle(element).getPropertyValue('--primary-color');
   console.log(primaryColor); // e.g., "#007bff"
   
               
   
                 
                   Copy
                 
               
             

2. Setting a Custom Property Value: Use setProperty() to set the value of a custom property. Because of the syntax parameter of the `@property` definition, Javascript-based setting can trigger value validation within the browser.

               
   element.style.setProperty('--primary-color', 'green');
   
               
   
                 
                   Copy
                 
               
             

Example: Dynamic Color Change with JavaScript

Let's illustrate how to create a dynamic color change using JavaScript and @property.

HTML:

            
<button class="my-button">Change Color</button>

            

              
                Copy
              
            
          

CSS:

            
@property --button-color {
  syntax: <color>;
  inherits: false;
  initial-value: #007bff;
}

.my-button {
  background-color: var(--button-color);
  color: white;
  padding: 10px 20px;
  border: none;
  cursor: pointer;
}

            

              
                Copy
              
            
          

JavaScript:

            
const button = document.querySelector('.my-button');

button.addEventListener('click', () => {
  const newColor = 'red'; // Could be based on some logic/input
  button.style.setProperty('--button-color', newColor);
});

            

              
                Copy
              
            
          

In this example, clicking the button changes the background color of the button by modifying the --button-color custom property using JavaScript.

Internationalization (i18n) and CSS @property

CSS @property can be a valuable tool in creating web applications that support different languages and locales. Here's how it can be applied to i18n:

• Typography: Define custom properties for font sizes, line heights, and font families, allowing you to adapt the text appearance based on the selected language.
• Layout: Utilize properties for spacing, margins, and padding to accommodate variations in text direction (e.g., left-to-right vs. right-to-left) and different character widths.
• Colors: Employ properties for UI element colors, such as button colors, text colors, and background colors. These can be adjusted to align with cultural preferences or design guidelines for specific regions.
• Text Direction: Use a custom property to control the text direction (e.g., ltr, rtl) and modify the layout accordingly.

Example: Adapting Font Sizes Based on Language

In this example, we demonstrate how to adapt the font size of headings according to the selected language. The approach would use a JavaScript library to determine the appropriate language and set custom properties.

            
@property --heading-font-size {
  syntax: <length>;
  inherits: false;
  initial-value: 2rem;
}

h1 {
  font-size: var(--heading-font-size);
}

            

              
                Copy
              
            
          

Then, dynamically set the value in JavaScript based on the detected language:

            
// Assuming a global variable or function to get the user's language
const userLanguage = getUserLanguage();
const heading = document.querySelector('h1');

if (userLanguage === 'ja') {
  heading.style.setProperty('--heading-font-size', '1.8rem'); // Adjust for Japanese
} else {
  heading.style.setProperty('--heading-font-size', '2rem'); // Default
}

            

              
                Copy
              
            
          

Accessibility Considerations

When working with @property, it's essential to keep accessibility in mind:

• Color Contrast: Ensure sufficient color contrast between text and backgrounds. Use custom properties for colors to easily update the design to meet contrast requirements.
• Text Size: Allow users to control text size. Use relative units (rem, em) and custom properties to make font scaling easy.
• Focus Indicators: Customize focus indicators to make them clearly visible. Use custom properties to control the color and style of the focus outlines.
• ARIA Attributes: Ensure that elements have the appropriate ARIA attributes when using custom properties to control states or behavior.
• Keyboard Navigation: Verify that your website is easily navigable using a keyboard, especially if custom properties are used to manage interactive elements.

Cross-Browser Considerations and Workarounds

While @property is a powerful tool, remember that browser support is not yet universally implemented. You should employ cross-browser techniques to mitigate the impact of lack of support.

• Progressive Enhancement: Design your styling with basic CSS variables, and then use the `@property` for added features in supported browsers.
• Feature Detection: Use feature detection methods to determine whether a browser supports @property before applying styles using it. A simple check can be done using JavaScript.
• CSS Fallbacks: Provide fallback values for properties that are not supported. This can be done by setting properties directly, or by using different variables for supported and non-supported browsers.
• Preprocessors: Utilize CSS preprocessors like Sass or Less to translate higher-level structures into standard CSS that can be used in browsers that don’t have full `@property` support. Although this introduces an extra step, the benefits often outweigh the drawbacks.

Example of a CSS Fallback:

            
.element {
  --base-color: #333; /* Default value for browsers without @property */
  color: var(--base-color);
}

@supports (color: --base-color) { /* Feature Detection for @property*/
  @property --base-color {
    syntax: <color>;
    inherits: false;
    initial-value: #333;
  }
  /* Add more complex styling here utilizing the @property */
}

            

              
                Copy
              
            
          

Tools and Libraries

Various tools and libraries can assist with working with @property:

• PostCSS Plugins: Plugins like `postcss-custom-properties` and `postcss-custom-properties-experimental` can help transform custom properties and provide support for older browsers by converting `@property` definitions into equivalent CSS rules.
• Stylelint: Integrate stylelint and custom rules or plugins to validate the usage and structure of your custom properties.
• Design System Frameworks: Integrate @property into popular design system frameworks such as Ant Design, Material UI, and Bootstrap to ensure design consistency and provide developers with a smoother experience.

Conclusion

CSS @property is a powerful addition to the web development toolkit, bringing structure, validation, and dynamic capabilities to custom properties. By defining the type and behavior of your CSS variables, you can enhance code maintainability, improve design consistency, and create more robust and predictable styling solutions.

As browser support improves, incorporating @property into your projects is increasingly important. By embracing the best practices outlined in this guide, you can leverage the benefits of this new feature and write more efficient, maintainable, and scalable CSS. Embrace @property, and transform your web development workflow!

Further Learning

• MDN Web Docs: @property
• CSS Custom Properties for Cascading Variables Module Level 1
• Can I Use: @property